home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_apache2.idb / usr / freeware / apache2 / include / apr_file_info.h.z / apr_file_info.h
C/C++ Source or Header  |  2002-07-08  |  15KB  |  394 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. #ifndef APR_FILE_INFO_H
  56. #define APR_FILE_INFO_H
  57.  
  58. #include "apr.h"
  59. #include "apr_user.h"
  60. #include "apr_pools.h"
  61. #include "apr_time.h"
  62. #include "apr_errno.h"
  63.  
  64. #if APR_HAVE_SYS_UIO_H
  65. #include <sys/uio.h>
  66. #endif
  67.  
  68. #ifdef __cplusplus
  69. extern "C" {
  70. #endif /* __cplusplus */
  71. /**
  72.  * @file apr_file_info.h
  73.  * @brief APR File handling
  74.  */
  75. /**
  76.  * @defgroup APR_File_Handle File Handling Functions
  77.  * @ingroup APR
  78.  * @{
  79.  */
  80.  
  81. typedef enum {
  82.     APR_NOFILE = 0,     /**< the file exists, but APR doesn't know its type */
  83.     APR_REG,            /**< a regular file */
  84.     APR_DIR,            /**< a directory */
  85.     APR_CHR,            /**< a character device */
  86.     APR_BLK,            /**< a block device */
  87.     APR_PIPE,           /**< a FIFO / pipe */
  88.     APR_LNK,            /**< a symbolic link */
  89.     APR_SOCK            /**< a [unix domain] socket */
  90. } apr_filetype_e; 
  91.  
  92. /**
  93.  * @defgroup APR_file_handle_permission File Permissions flags 
  94.  * @{
  95.  */
  96.  
  97. #define APR_UREAD       0x0400 /**< Read by user */
  98. #define APR_UWRITE      0x0200 /**< Write by user */
  99. #define APR_UEXECUTE    0x0100 /**< Execute by user */
  100.  
  101. #define APR_GREAD       0x0040 /**< Read by group */
  102. #define APR_GWRITE      0x0020 /**< Write by group */
  103. #define APR_GEXECUTE    0x0010 /**< Execute by group */
  104.  
  105. #define APR_WREAD       0x0004 /**< Read by others */
  106. #define APR_WWRITE      0x0002 /**< Write by others */
  107. #define APR_WEXECUTE    0x0001 /**< Execute by others */
  108.  
  109. #define APR_OS_DEFAULT  0x0FFF /**< use OS's default permissions */
  110.  
  111. /* additional permission flags for apr_file_copy  and apr_file_append */
  112. #define APR_FILE_SOURCE_PERMS 0x1000 /**< Copy source file's permissions */
  113.  
  114. /** @} */
  115.  
  116.  
  117. /**
  118.  * Structure for referencing directories.
  119.  * @defvar apr_dir_t
  120.  */
  121. typedef struct apr_dir_t          apr_dir_t;
  122. /**
  123.  * Structure for determining file permissions.
  124.  * @defvar apr_fileperms_t
  125.  */
  126. typedef apr_int32_t               apr_fileperms_t;
  127. #if (defined WIN32) || (defined NETWARE)
  128. /**
  129.  * Structure for determining the inode of the file.
  130.  * @defvar apr_ino_t
  131.  */
  132. typedef apr_uint64_t              apr_ino_t;
  133. /**
  134.  * Structure for determining the device the file is on.
  135.  */
  136. typedef apr_uint32_t              apr_dev_t;
  137. #else
  138. /** The inode of the file. */
  139. typedef ino_t                     apr_ino_t;
  140. /**
  141.  * Structure for determining the device the file is on.
  142.  */
  143. typedef dev_t                     apr_dev_t;
  144. #endif
  145.  
  146. /**
  147.  * @defgroup APR_File_Info Stat Functions
  148.  * @{
  149.  */
  150. typedef struct apr_finfo_t        apr_finfo_t;
  151.  
  152. #define APR_FINFO_LINK   0x00000001 /**< Stat the link not the file itself if it is a link */
  153. #define APR_FINFO_MTIME  0x00000010 /**< Modification Time */
  154. #define APR_FINFO_CTIME  0x00000020 /**< Creation Time */
  155. #define APR_FINFO_ATIME  0x00000040 /**< Access Time */
  156. #define APR_FINFO_SIZE   0x00000100 /**< Size of the file */
  157. #define APR_FINFO_CSIZE  0x00000200 /**< Storage size consumed by the file */
  158. #define APR_FINFO_DEV    0x00001000
  159. #define APR_FINFO_INODE  0x00002000
  160. #define APR_FINFO_NLINK  0x00004000
  161. #define APR_FINFO_TYPE   0x00008000
  162. #define APR_FINFO_USER   0x00010000 
  163. #define APR_FINFO_GROUP  0x00020000 
  164. #define APR_FINFO_UPROT  0x00100000 
  165. #define APR_FINFO_GPROT  0x00200000
  166. #define APR_FINFO_WPROT  0x00400000
  167. #define APR_FINFO_ICASE  0x01000000  /**<  if dev is case insensitive */
  168. #define APR_FINFO_NAME   0x02000000  /**<  ->name in proper case */
  169.  
  170. #define APR_FINFO_MIN    0x00008170  /**<  type, mtime, ctime, atime, size */
  171. #define APR_FINFO_IDENT  0x00003000  /**<  dev and inode */
  172. #define APR_FINFO_OWNER  0x00030000  /**<  user and group */
  173. #define APR_FINFO_PROT   0x00700000  /**<  all protections */
  174. #define APR_FINFO_NORM   0x0073b170  /**<  an atomic unix apr_stat() */
  175. #define APR_FINFO_DIRENT 0x02000000  /**<  an atomic unix apr_dir_read() */
  176.  
  177. /**
  178.  * The file information structure.  This is analogous to the POSIX
  179.  * stat structure.
  180.  */
  181. struct apr_finfo_t {
  182.     /** Allocates memory and closes lingering handles in the specified pool */
  183.     apr_pool_t *pool;
  184.     /** The bitmask describing valid fields of this apr_finfo_t structure 
  185.      *  including all available 'wanted' fields and potentially more */
  186.     apr_int32_t valid;
  187.     /** The access permissions of the file.  Mimics Unix access rights. */
  188.     apr_fileperms_t protection;
  189.     /** The type of file.  One of APR_NOFILE, APR_REG, APR_DIR, APR_CHR, 
  190.      *  APR_BLK, APR_PIPE, APR_LNK, APR_SOCK 
  191.      */
  192.     apr_filetype_e filetype;
  193.     /** The user id that owns the file */
  194.     apr_uid_t user;
  195.     /** The group id that owns the file */
  196.     apr_gid_t group;
  197.     /** The inode of the file. */
  198.     apr_ino_t inode;
  199.     /** The id of the device the file is on. */
  200.     apr_dev_t device;
  201.     /** The number of hard links to the file. */
  202.     apr_int32_t nlink;
  203.     /** The size of the file */
  204.     apr_off_t size;
  205.     /** The storage size consumed by the file */
  206.     apr_off_t csize;
  207.     /** The time the file was last accessed */
  208.     apr_time_t atime;
  209.     /** The time the file was last modified */
  210.     apr_time_t mtime;
  211.     /** The time the file was last changed */
  212.     apr_time_t ctime;
  213.     /** The full pathname of the file */
  214.     const char *fname;
  215.     /** The file's name (no path) in filesystem case */
  216.     const char *name;
  217.     /** The file's handle, if accessed (can be submitted to apr_duphandle) */
  218.     struct apr_file_t *filehand;
  219. };
  220.  
  221. /**
  222.  * get the specified file's stats.  The file is specified by filename, 
  223.  * instead of using a pre-opened file.
  224.  * @param finfo Where to store the information about the file, which is
  225.  * never touched if the call fails.
  226.  * @param fname The name of the file to stat.
  227.  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values 
  228.  * @param cont the pool to use to allocate the new file. 
  229.  */ 
  230. APR_DECLARE(apr_status_t) apr_stat(apr_finfo_t *finfo, const char *fname,
  231.                                    apr_int32_t wanted, apr_pool_t *cont);
  232.  
  233. /**
  234.  * get the specified file's stats.  The file is specified by filename, 
  235.  * instead of using a pre-opened file.  If the file is a symlink, this function
  236.  * will get the stats for the symlink not the file the symlink refers to.
  237.  * @param finfo Where to store the information about the file, which is
  238.  * never touched if the call fails.
  239.  * @param fname The name of the file to stat.
  240.  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values 
  241.  * @param cont the pool to use to allocate the new file. 
  242.  * @deprecated This function is depreciated, it's equivilant to calling apr_stat with 
  243.  * the wanted flag value APR_FINFO_LINK
  244.  */ 
  245. APR_DECLARE(apr_status_t) apr_lstat(apr_finfo_t *finfo, const char *fname,
  246.                                     apr_int32_t wanted, apr_pool_t *cont);
  247. /** @} */
  248. /**
  249.  * @defgroup APR_DIRECTORY Directory Manipulation Functions
  250.  * @{
  251.  */
  252.  
  253. /**
  254.  * Open the specified directory.
  255.  * @param new_dir The opened directory descriptor.
  256.  * @param dirname The full path to the directory (use / on all systems)
  257.  * @param cont The pool to use.
  258.  */                        
  259. APR_DECLARE(apr_status_t) apr_dir_open(apr_dir_t **new_dir, 
  260.                                        const char *dirname, 
  261.                                        apr_pool_t *cont);
  262.  
  263. /**
  264.  * close the specified directory. 
  265.  * @param thedir the directory descriptor to close.
  266.  */                        
  267. APR_DECLARE(apr_status_t) apr_dir_close(apr_dir_t *thedir);
  268.  
  269. /**
  270.  * Read the next entry from the specified directory. 
  271.  * @param finfo the file info structure and filled in by apr_dir_read
  272.  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values 
  273.  * @param thedir the directory descriptor returned from apr_dir_open
  274.  * @remark All systems return . and .. as the first two files.
  275.  */                        
  276. APR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t wanted,
  277.                                        apr_dir_t *thedir);
  278.  
  279. /**
  280.  * Rewind the directory to the first entry.
  281.  * @param thedir the directory descriptor to rewind.
  282.  */                        
  283. APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir);
  284. /** @} */
  285.  
  286. /**
  287.  * @defgroup apr_filepath FilePath Manipulation operations 
  288.  * @{
  289.  */
  290.  
  291. /** Cause apr_filepath_merge to fail if addpath is above rootpath */
  292. #define APR_FILEPATH_NOTABOVEROOT   0x01
  293.  
  294. /** internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */
  295. #define APR_FILEPATH_SECUREROOTTEST 0x02
  296.  
  297. /** Cause apr_filepath_merge to fail if addpath is above rootpath,
  298.  * even given a rootpath /foo/bar and an addpath ../bar/bash
  299.  */
  300. #define APR_FILEPATH_SECUREROOT     0x03
  301.  
  302. /** Fail apr_filepath_merge if the merged path is relative */
  303. #define APR_FILEPATH_NOTRELATIVE    0x04
  304.  
  305. /** Fail apr_filepath_merge if the merged path is absolute */
  306. #define APR_FILEPATH_NOTABSOLUTE    0x08
  307.  
  308. /** Return the file system's native path format (e.g. path delimiters
  309.  * of ':' on MacOS9, '\' on Win32, etc.) */
  310. #define APR_FILEPATH_NATIVE         0x10
  311.  
  312. /** Resolve the true case of existing directories and file elements
  313.  * of addpath, (resolving any aliases on Win32) and append a proper 
  314.  * trailing slash if a directory
  315.  */
  316. #define APR_FILEPATH_TRUENAME       0x20
  317. /** @} */
  318. /**
  319.  * Extract the rootpath from the given filepath
  320.  * @ingroup apr_filepath
  321.  * @param rootpath the root file path returned with APR_SUCCESS or APR_EINCOMPLETE
  322.  * @param filepath the pathname to parse for its root component
  323.  * @param flags the desired rules to apply, from
  324.  * <PRE>
  325.  *      APR_FILEPATH_NATIVE    Use native path seperators (e.g. '\' on Win32)
  326.  *      APR_FILEPATH_TRUENAME  Tests that the root exists, and makes it proper
  327.  * </PRE>
  328.  * @param p the pool to allocate the new path string from
  329.  * @deffunc apr_status_t apr_filepath_root(const char **rootpath, const char **inpath, apr_int32_t flags, apr_pool_t *p)
  330.  * @remark on return, filepath points to the first non-root character in the
  331.  * given filepath.  In the simplest example, given a filepath of "/foo", 
  332.  * returns the rootpath of "/" and filepath points at "foo".  This is far 
  333.  * more complex on other platforms, which will canonicalize the root form
  334.  * to a consistant format, given the APR_FILEPATH_TRUENAME flag, and also
  335.  * test for the validity of that root (e.g., that a drive d:/ or network 
  336.  * share //machine/foovol/). 
  337.  * The function returns APR_ERELATIVE if filepath isn't rooted (an
  338.  * error), APR_EINCOMPLETE if the root path is ambigious (but potentially
  339.  * legitimate, e.g. "/" on Windows is incomplete because it doesn't specify
  340.  * the drive letter), or APR_EBADPATH if the root is simply invalid.
  341.  * APR_SUCCESS is returned if filepath is an absolute path.
  342.  */
  343. APR_DECLARE(apr_status_t) apr_filepath_root(const char **rootpath, 
  344.                                             const char **filepath, 
  345.                                             apr_int32_t flags,
  346.                                             apr_pool_t *p);
  347.  
  348. /**
  349.  * Merge additional file path onto the previously processed rootpath
  350.  * @ingroup apr_filepath
  351.  * @param newpath the merged paths returned
  352.  * @param rootpath the root file path (NULL uses the current working path)
  353.  * @param addpath the path to add to the root path
  354.  * @param flags the desired APR_FILEPATH_ rules to apply when merging
  355.  * @param p the pool to allocate the new path string from
  356.  * @deffunc apr_status_t apr_filepath_merge(char **newpath, const char *rootpath, const char *addpath, apr_int32_t flags, apr_pool_t *p)
  357.  */                        
  358. APR_DECLARE(apr_status_t) apr_filepath_merge(char **newpath, 
  359.                                              const char *rootpath,
  360.                                              const char *addpath, 
  361.                                              apr_int32_t flags,
  362.                                              apr_pool_t *p);
  363.  
  364. /**
  365.  * Return the default file path (for relative file names)
  366.  * @ingroup apr_filepath
  367.  * @param path the default path string returned
  368.  * @param flags optional flag APR_FILEPATH_NATIVE to retrieve the
  369.  *              default file path in os-native format.
  370.  * @param p the pool to allocate the default path string from
  371.  * @deffunc apr_status_t apr_filepath_get(char **path, apr_int32_t flags, apr_pool_t *p)
  372.  */
  373. APR_DECLARE(apr_status_t) apr_filepath_get(char **path, apr_int32_t flags,
  374.                                            apr_pool_t *p);
  375.  
  376. /**
  377.  * Set the default file path (for relative file names)
  378.  * @ingroup apr_filepath
  379.  * @param path the default path returned
  380.  * @param p the pool to allocate any working storage
  381.  * @deffunc apr_status_t apr_filepath_get(char **defpath, apr_pool_t *p)
  382.  */
  383. APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t *p);
  384.  
  385. /** @} */
  386.  
  387. #ifdef __cplusplus
  388. }
  389. #endif
  390.  
  391. #endif  /* ! APR_FILE_INFO_H */
  392.  
  393.  
  394.